+++ /dev/null
-<!-- ##### SECTION Title ##### -->
-GtkMenu
-
-<!-- ##### SECTION Short_Description ##### -->
-A menu widget
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-A #GtkMenu is a #GtkMenuShell that implements a drop down menu consisting of
-a list of #GtkMenuItem objects which can be navigated and activated by the
-user to perform application functions.
-</para>
-
-<para>
-A #GtkMenu is most commonly dropped down by activating a #GtkMenuItem in a
-#GtkMenuBar or popped up by activating a #GtkMenuItem in another #GtkMenu.
-</para>
-
-<para>
-A #GtkMenu can also be popped up by activating a #GtkOptionMenu.
-Other composite widgets such as the #GtkNotebook can pop up a #GtkMenu
-as well.
-</para>
-
-<para>
-Applications can display a #GtkMenu as a popup menu by calling the
-gtk_menu_popup() function. The example below shows how an application
-can pop up a menu when the 3rd mouse button is pressed.
-</para>
-
-<example>
-<title>Connecting the popup signal handler.</title>
-<programlisting>
- /* connect our handler which will popup the menu */
- g_signal_connect_swapped (window, "button_press_event",
- G_CALLBACK (my_popup_handler), menu);
-</programlisting>
-</example>
-
-<example>
-<title>Signal handler which displays a popup menu.</title>
-<programlisting>
-static gint
-my_popup_handler (GtkWidget *widget, GdkEvent *event)
-{
- GtkMenu *menu;
- GdkEventButton *event_button;
-
- g_return_val_if_fail (widget != NULL, FALSE);
- g_return_val_if_fail (GTK_IS_MENU (widget), FALSE);
- g_return_val_if_fail (event != NULL, FALSE);
-
- /* The "widget" is the menu that was supplied when
- * g_signal_connect_swapped() was called.
- */
- menu = GTK_MENU (widget);
-
- if (event->type == GDK_BUTTON_PRESS)
- {
- event_button = (GdkEventButton *) event;
- if (event_button->button == 3)
- {
- gtk_menu_popup (menu, NULL, NULL, NULL, NULL,
- event_button->button, event_button->time);
- return TRUE;
- }
- }
-
- return FALSE;
-}
-</programlisting>
-</example>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkMenu ##### -->
-<para>
-The #GtkMenu struct contains private data only, and
-should be accessed using the functions below.
-</para>
-
-
-<!-- ##### SIGNAL GtkMenu::move-scroll ##### -->
-<para>
-
-</para>
-
-@menu: the object which received the signal.
-@arg1:
-
-<!-- ##### ARG GtkMenu:accel-group ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:accel-path ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:active ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:attach-widget ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:monitor ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:reserve-toggle-size ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:tearoff-state ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:tearoff-title ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:bottom-attach ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:left-attach ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:right-attach ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:top-attach ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:arrow-placement ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:arrow-scaling ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:double-arrows ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:horizontal-offset ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:horizontal-padding ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:vertical-offset ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMenu:vertical-padding ##### -->
-<para>
-
-</para>
-
-<!-- ##### FUNCTION gtk_menu_new ##### -->
-<para>
-Creates a new #GtkMenu.
-</para>
-
-@void:
-@Returns: a new #GtkMenu.
-
-
-<!-- ##### FUNCTION gtk_menu_set_screen ##### -->
-<para>
-
-</para>
-
-@menu:
-@screen:
-
-
-<!-- ##### FUNCTION gtk_menu_reorder_child ##### -->
-<para>
-Moves a #GtkMenuItem to a new position within the #GtkMenu.
-</para>
-
-@menu: a #GtkMenu.
-@child: the #GtkMenuItem to move.
-@position: the new position to place @child. Positions are numbered from
-0 to n-1.
-
-
-<!-- ##### FUNCTION gtk_menu_attach ##### -->
-<para>
-
-</para>
-
-@menu:
-@child:
-@left_attach:
-@right_attach:
-@top_attach:
-@bottom_attach:
-
-
-<!-- ##### FUNCTION gtk_menu_popup_for_device ##### -->
-<para>
-
-</para>
-
-@menu:
-@device:
-@parent_menu_shell:
-@parent_menu_item:
-@func:
-@data:
-@destroy:
-@button:
-@activate_time:
-
-
-<!-- ##### FUNCTION gtk_menu_popup ##### -->
-
-
-@menu:
-@parent_menu_shell:
-@parent_menu_item:
-@func:
-@data:
-@button:
-@activate_time:
-
-
-<!-- ##### FUNCTION gtk_menu_set_accel_group ##### -->
-<para>
-Set the #GtkAccelGroup which holds global accelerators for the menu.
-This accelerator group needs to also be added to all windows that
-this menu is being used in with gtk_window_add_accel_group(), in order
-for those windows to support all the accelerators contained in this group.
-</para>
-
-@menu: a #GtkMenu.
-@accel_group: the #GtkAccelGroup to be associated with the menu.
-
-
-<!-- ##### FUNCTION gtk_menu_get_accel_group ##### -->
-<para>
-Gets the #GtkAccelGroup which holds global accelerators for the menu.
-See gtk_menu_set_accel_group().
-</para>
-
-@menu: a #GtkMenu.
-@Returns: the #GtkAccelGroup associated with the menu.
-
-
-<!-- ##### FUNCTION gtk_menu_set_accel_path ##### -->
-<para>
-
-</para>
-
-@menu:
-@accel_path:
-
-
-<!-- ##### FUNCTION gtk_menu_get_accel_path ##### -->
-<para>
-
-</para>
-
-@menu:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_menu_set_title ##### -->
-<para>
-</para>
-
-@menu:
-@title:
-
-
-<!-- ##### FUNCTION gtk_menu_get_title ##### -->
-<para>
-
-</para>
-
-@menu:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_menu_set_monitor ##### -->
-<para>
-
-</para>
-
-@menu:
-@monitor_num:
-
-
-<!-- ##### FUNCTION gtk_menu_get_monitor ##### -->
-<para>
-
-</para>
-
-@menu:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_menu_get_tearoff_state ##### -->
-<para>
-
-</para>
-
-@menu:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_menu_set_reserve_toggle_size ##### -->
-<para>
-
-</para>
-
-@menu:
-@reserve_toggle_size:
-
-
-<!-- ##### FUNCTION gtk_menu_get_reserve_toggle_size ##### -->
-<para>
-
-</para>
-
-@menu:
-@Returns:
-
-
-<!-- ##### FUNCTION gtk_menu_popdown ##### -->
-<para>
-Removes the menu from the screen.
-</para>
-
-@menu: a #GtkMenu.
-
-
-<!-- ##### FUNCTION gtk_menu_reposition ##### -->
-<para>
-Repositions the menu according to its position function.
-</para>
-
-@menu: a #GtkMenu.
-
-
-<!-- ##### FUNCTION gtk_menu_get_active ##### -->
-<para>
-Returns the selected menu item from the menu. This is used by the
-#GtkOptionMenu.
-</para>
-
-@menu: a #GtkMenu.
-@Returns: the #GtkMenuItem that was last selected in the menu. If a
-selection has not yet been made, the first menu item is selected.
-
-
-<!-- ##### FUNCTION gtk_menu_set_active ##### -->
-<para>
-Selects the specified menu item within the menu. This is used by the
-#GtkOptionMenu and should not be used by anyone else.
-</para>
-
-@menu: a #GtkMenu.
-@index_: the index of the menu item to select. Index values are from
-0 to n-1.
-
-
-<!-- ##### FUNCTION gtk_menu_set_tearoff_state ##### -->
-<para>
-Changes the tearoff state of the menu. A menu is normally displayed
-as drop down menu which persists as long as the menu is active. It can
-also be displayed as a tearoff menu which persists until it is closed
-or reattached.
-</para>
-
-@menu: a #GtkMenu.
-@torn_off: If %TRUE, menu is displayed as a tearoff menu.
-
-
-<!-- ##### FUNCTION gtk_menu_attach_to_widget ##### -->
-<para>
-Attaches the menu to the widget and provides a callback function that will
-be invoked when the menu calls gtk_menu_detach() during its destruction.
-</para>
-
-@menu: a #GtkMenu.
-@attach_widget: the #GtkWidget that the menu will be attached to.
-@detacher: the user supplied callback function that will be called when
-the menu calls gtk_menu_detach().
-
-
-<!-- ##### FUNCTION gtk_menu_detach ##### -->
-<para>
-Detaches the menu from the widget to which it had been attached.
-This function will call the callback function, @detacher, provided
-when the gtk_menu_attach_to_widget() function was called.
-</para>
-
-@menu: a #GtkMenu.
-
-
-<!-- ##### FUNCTION gtk_menu_get_attach_widget ##### -->
-<para>
-Returns the #GtkWidget that the menu is attached to.
-</para>
-
-@menu: a #GtkMenu.
-@Returns: the #GtkWidget that the menu is attached to.
-
-
-<!-- ##### FUNCTION gtk_menu_get_for_attach_widget ##### -->
-<para>
-
-</para>
-
-@widget:
-@Returns:
-
-
-<!-- ##### USER_FUNCTION GtkMenuPositionFunc ##### -->
-<para>
-A user function supplied when calling gtk_menu_popup() which controls the
-positioning of the menu when it is displayed. The function sets the @x
-and @y parameters to the coordinates where the menu is to be drawn.
-To make the menu appear on a different monitor than the mouse pointer,
-gtk_menu_set_monitor() must be called.
-</para>
-
-@menu: a #GtkMenu.
-@x: address of the #gint representing the horizontal position where the
-menu shall be drawn. This is an output parameter.
-@y: address of the #gint representing the vertical position where the
-menu shall be drawn. This is an output parameter.
-@push_in: This parameter controls how menus placed outside the monitor are handled.
- If this is set to %TRUE and part of the menu is outside the monitor then
- GTK+ pushes the window into the visible area, effectively modifying the
- popup position.
- Note that moving and possibly resizing the menu around will alter the
- scroll position to keep the menu items "in place", i.e. at the same monitor
- position they would have been without resizing.
- In practice, this behavior is only useful for combobox popups or option
- menus and cannot be used to simply confine a menu to monitor boundaries.
- In that case, changing the scroll offset is not desirable.
-@user_data: the data supplied by the user in the gtk_menu_popup() @data
-parameter.
-
-
-<!-- ##### USER_FUNCTION GtkMenuDetachFunc ##### -->
-<para>
-A user function supplied when calling gtk_menu_attach_to_widget() which
-will be called when the menu is later detached from the widget.
-</para>
-
-@attach_widget: the #GtkWidget that the menu is being detached from.
-@menu: the #GtkMenu being detached.
-
-
* GTK+ at ftp://ftp.gtk.org/pub/gtk/.
*/
+/**
+ * SECTION:gtkmenu
+ * @Short_description: A menu widget
+ * @Title: GtkMenu
+ *
+ * A #GtkMenu is a #GtkMenuShell that implements a drop down menu
+ * consisting of a list of #GtkMenuItem objects which can be navigated
+ * and activated by the user to perform application functions.
+ *
+ * A #GtkMenu is most commonly dropped down by activating a
+ * #GtkMenuItem in a #GtkMenuBar or popped up by activating a
+ * #GtkMenuItem in another #GtkMenu.
+ *
+ * A #GtkMenu can also be popped up by activating a #GtkOptionMenu.
+ * Other composite widgets such as the #GtkNotebook can pop up a
+ * #GtkMenu as well.
+ *
+ * Applications can display a #GtkMenu as a popup menu by calling the
+ * gtk_menu_popup() function. The example below shows how an application
+ * can pop up a menu when the 3rd mouse button is pressed.
+ *
+ * <example>
+ * <title>Connecting the popup signal handler.</title>
+ * <programlisting>
+ * /<!---->* connect our handler which will popup the menu *<!---->/
+ * g_signal_connect_swapped (window, "button_press_event",
+ * G_CALLBACK (my_popup_handler), menu);
+ * </programlisting>
+ * </example>
+ *
+ * <example>
+ * <title>Signal handler which displays a popup menu.</title>
+ * <programlisting>
+ * static gint
+ * my_popup_handler (GtkWidget *widget, GdkEvent *event)
+ * {
+ * GtkMenu *menu;
+ * GdkEventButton *event_button;
+ *
+ * g_return_val_if_fail (widget != NULL, FALSE);
+ * g_return_val_if_fail (GTK_IS_MENU (widget), FALSE);
+ * g_return_val_if_fail (event != NULL, FALSE);
+ *
+ * /<!---->* The "widget" is the menu that was supplied when
+ * * g_signal_connect_swapped() was called.
+ * *<!---->/
+ * menu = GTK_MENU (widget);
+ *
+ * if (event->type == GDK_BUTTON_PRESS)
+ * {
+ * event_button = (GdkEventButton *) event;
+ * if (event_button->button == 3)
+ * {
+ * gtk_menu_popup (menu, NULL, NULL, NULL, NULL,
+ * event_button->button, event_button->time);
+ * return TRUE;
+ * }
+ * }
+ *
+ * return FALSE;
+ * }
+ * </programlisting>
+ * </example>
+ */
+
#include "config.h"
#include <string.h>
menu_shell_class->get_popup_delay = gtk_menu_get_popup_delay;
menu_shell_class->move_current = gtk_menu_move_current;
+ /**
+ * GtkMenu::move-scroll:
+ * @menu: a #GtkMenu
+ * @scroll_type: a #GtkScrollType
+ */
menu_signals[MOVE_SCROLL] =
g_signal_new_class_handler (I_("move-scroll"),
G_OBJECT_CLASS_TYPE (gobject_class),
GTK_PARAM_READWRITE));
/**
- * GtkMenu::arrow-scaling
+ * GtkMenu:arrow-scaling
*
* Arbitrary constant to scale down the size of the scroll arrow.
*
menu_change_screen (menu, gtk_widget_get_screen (attach_widget));
}
+/**
+ * gtk_menu_attach_to_widget:
+ * @menu: a #GtkMenu
+ * @attach_widget: the #GtkWidget that the menu will be attached to
+ * @detacher: the user supplied callback functions that will be called
+ * when the menu calls gtk_menu_detach()
+ *
+ * Attaches the menu to the widget and provides a callback function
+ * that will be invoked when the menu calls gtk_menu_detach() during
+ * its destruction.
+ */
void
gtk_menu_attach_to_widget (GtkMenu *menu,
GtkWidget *attach_widget,
g_object_notify (G_OBJECT (menu), "attach-widget");
}
+/**
+ * gtk_menu_get_attach_widget:
+ * @menu: a #GtkMenu
+ *
+ * Returns the #GtkWidget that the menu is attached to.
+ *
+ * Returns: the #GtkWidget that the menu is attached to
+ */
GtkWidget*
gtk_menu_get_attach_widget (GtkMenu *menu)
{
return NULL;
}
+/**
+ * gtk_menu_detach:
+ * @menu: a #GtkMenu
+ *
+ * Detaches the menu from the widget to which it had been attached.
+ * This function will call the callback function, @detacher, provided
+ * when the gtk_menu_attach_to_widget() function was called.
+ */
void
gtk_menu_detach (GtkMenu *menu)
{
menu_queue_resize (menu);
}
+/**
+ * gtk_menu_new:
+ *
+ * Creates a new #GtkMenu.
+ *
+ * Returns: a new #GtkMenu.
+ */
GtkWidget*
gtk_menu_new (void)
{
button, activate_time);
}
+/**
+ * gtk_menu_popdown:
+ * @menu: a #GtkMenu
+ *
+ * Removes the menu from the screen.
+ */
void
gtk_menu_popdown (GtkMenu *menu)
{
menu_grab_transfer_window_destroy (menu);
}
+/**
+ * gtk_menu_get_active:
+ * @menu: a #GtkMenu
+ *
+ * Returns the selected menu item from the menu. This is used by the
+ * #GtkOptionMenu.
+ *
+ * Returns: the #GtkMenuItem that was last selected in the menu. If a
+ * selection has not yet been made, the first menu item is
+ * selected.
+ */
GtkWidget*
gtk_menu_get_active (GtkMenu *menu)
{
return priv->old_active_menu_item;
}
+/**
+ * gtk_menu_set_active:
+ * @menu: a #GtkMenu
+ * @index: the index of the menu item to select. Iindex values are
+ * from 0 to n-1
+ *
+ * Selects the specified menu item within the menu. This is used by
+ * the #GtkOptionMenu and should not be used by anyone else.
+ */
void
gtk_menu_set_active (GtkMenu *menu,
guint index)
/**
* gtk_menu_set_accel_group:
- * @accel_group: (allow-none):
+ * @menu: a #GtkMenu
+ * @accel_group: (allow-none): the #GtkAccelGroup to be associated
+ * with the menu.
+ *
+ * Set the #GtkAccelGroup which holds global accelerators for the
+ * menu. This accelerator group needs to also be added to all windows
+ * that this menu is being used in with gtk_window_add_accel_group(),
+ * in order for those windows to support all the accelerators
+ * contained in this group.
*/
void
gtk_menu_set_accel_group (GtkMenu *menu,
}
}
+/**
+ * gtk_menu_get_accel_group:
+ * @menu a #GtkMenu
+ *
+ * Gets the #GtkAccelGroup which holds global accelerators for the
+ * menu. See gtk_menu_set_accel_group().
+ *
+ * Returns: the #GtkAccelGroup associated with the menu.
+ */
GtkAccelGroup*
gtk_menu_get_accel_group (GtkMenu *menu)
{
}
}
+/**
+ * gtk_menu_reposition:
+ * @menu: a #GtkMenu
+ *
+ * Repositions the menu according to its position function.
+ */
void
gtk_menu_reposition (GtkMenu *menu)
{
gtk_menu_set_tearoff_state (menu, FALSE);
}
+/**
+ * gtk_menu_set_tearoff_state:
+ * @menu: a #GtkMenu
+ * @torn_off: If %TRUE, menu is displayed as a tearoff menu.
+ *
+ * Changes the tearoff state of the menu. A menu is normally
+ * displayed as drop down menu which persists as long as the menu is
+ * active. It can also be displayed as a tearoff menu which persists
+ * until it is closed or reattached.
+ */
void
gtk_menu_set_tearoff_state (GtkMenu *menu,
gboolean torn_off)
return menu->priv->title;
}
+/**
+ * gtk_menu_reorder_child:
+ * @menu: a #GtkMenu
+ * @child: the #GtkMenuItem to move
+ * @position: the new position to place @child. Positions are
+ * numbered from 0 to n-1.
+ */
void
gtk_menu_reorder_child (GtkMenu *menu,
GtkWidget *child,
typedef struct _GtkMenuClass GtkMenuClass;
typedef struct _GtkMenuPrivate GtkMenuPrivate;
+/**
+ * GtkMenuPositionFunc:
+ * @menu: a #GtkMenu.
+ * @x: (out): address of the #gint representing the horizontal
+ * position where the menu shall be drawn.
+ * @y: (out): address of the #gint representing the vertical position
+ * where the menu shall be drawn. This is an output parameter.
+ * @push_in: (inout): This parameter controls how menus placed outside
+ * the monitor are handled. If this is set to %TRUE and part of
+ * the menu is outside the monitor then GTK+ pushes the window
+ * into the visible area, effectively modifying the popup
+ * position. Note that moving and possibly resizing the menu
+ * around will alter the scroll position to keep the menu items
+ * "in place", i.e. at the same monitor position they would have
+ * been without resizing. In practice, this behavior is only
+ * useful for combobox popups or option menus and cannot be used
+ * to simply confine a menu to monitor boundaries. In that case,
+ * changing the scroll offset is not desirable.
+ * @user_data: the data supplied by the user in the gtk_menu_popup()
+ * @data parameter.
+ *
+ * A user function supplied when calling gtk_menu_popup() which
+ * controls the positioning of the menu when it is displayed. The
+ * function sets the @x and @y parameters to the coordinates where the
+ * menu is to be drawn. To make the menu appear on a different
+ * monitor than the mouse pointer, gtk_menu_set_monitor() must be
+ * called.
+ */
typedef void (*GtkMenuPositionFunc) (GtkMenu *menu,
gint *x,
gint *y,
gboolean *push_in,
gpointer user_data);
+
+/**
+ * GtkMenuDetachFunc:
+ * @attach_widget: the #GtkWidget that the menu is being detached from.
+ * @menu: the #GtkMenu being detached.
+ *
+ * A user function supplied when calling gtk_menu_attach_to_widget() which
+ * will be called when the menu is later detached from the widget.
+ */
typedef void (*GtkMenuDetachFunc) (GtkWidget *attach_widget,
GtkMenu *menu);
*/
GtkWidget* gtk_menu_get_active (GtkMenu *menu);
void gtk_menu_set_active (GtkMenu *menu,
- guint index_);
+ guint index);
/* set/get the accelerator group that holds global accelerators (should
* be added to the corresponding toplevel with gtk_window_add_accel_group().
projects / gtk4.git / commitdiff